Inside Macintosh: QuickDraw GX Graphics /

Chapter 4 - Geometric Operations / Geometric Operations Reference

Functions / Incorporating Style Information Into Shape Geometries

GXPrimitiveShape

You can use the GXPrimitiveShape function to convert a shape to its primitive form.

void GXPrimitiveShape(gxShape target);

target

A reference to the shape to convert to primitive form.

DESCRIPTION

The GXPrimitiveShape function converts the shape referenced by the target parameter to its primitive form--that is, it changes the geometry, shape fill, and shape type of the target shape to incorporate the information from the original shape's style (including pen width, dashes, joins, and so on).

For example, a horizontal line shape with a greater-than-zero pen width becomes a filled rectangle shape. A diagonal line shape with a greater-than-zero pen width becomes a filled polygon shape. A curve shape with a greater-than-zero pen width becomes a filled path shape. A framed shape dashed with rectangles becomes a polygon shape with multiple contours--each contour representing one of the original dashes.

For the geometric shapes, the shape resulting from this function can be a hairline shape or a solid-filled shape. In either case, the information from the style object is no longer necessary because it has been incorporated into the shape object itself.

Implementation Note

In version 1.0 of QuickDraw GX, this function posts an error of functionality_unimplemented for picture shapes.

The result of the GXPrimitiveShape function is not simplified, nor are its unnecessary geometric points removed. You may want to simplify or reduce the resulting shape by calling the GXSimplifyShape function or the GXReduceShape function.

The following table gives information about this function for each type of geometric shape:

Shape type	Action taken
empty	If the shape fill is the noFill shape fill, this function posts the notice shape_already_in_primitive_form. If the shape fill is either of the inverse shape fills, this function returns a full shape (unless the shape has a pattern, in which case the function returns the shape described by the pattern).
full	If the shape fill is the noFill shape fill or any of the inverse fills, this function returns an empty shape. Otherwise, the function posts the notice shape_already_in_primitive_form (unless the shape has a pattern, in which case the function returns the shape described by the pattern).
point	If the shape fill is the noFill shape fill, this function returns an empty shape. If the pen width is greater than zero and the shape has a start cap, the function returns the start cap. If the pen width is zero or the shape has no start cap, the function returns an empty shape. If the shape has a pen width of zero, no start cap, and a solid pattern, the function returns a point as indicated by the pattern. If the shape has a framed pattern, the function posts the clip_to_frame_shape_unimplemented error. Bitmap patterns are ignored. If one of the grid-constraining attributes is set, this function constrains the point geometry to the grid.
line	If the shape fill is the noFill shape fill, this function returns an empty shape. If the pen width is greater than zero, the function returns a polygon shape (or a path shape depending on the start and end caps). If the pen width is zero and the shape has a solid pattern, the function returns a point or a line as indicated by the pattern. If the shape has a framed pattern, the function posts the clip_to_frame_shape_unimplemented error. Bitmap patterns are ignored. If one of the grid-constraining attributes is set, this function constrains the geometry to the grid.
curve	If the shape fill is the noFill shape fill, this function returns an empty shape. If the pen width is greater than zero, the function returns a path shape. If the pen width is zero and the shape has a solid pattern, the function returns a point, line, curve, or path line as indicated by the pattern. If the shape has a framed pattern, the function posts the clip_to_frame_shape_unimplemented error. Bitmap patterns are ignored. If one of the grid-constraining attributes is set, this function constrains the geometry to the grid.
rectangle	If the shape fill is the noFill shape fill, this function returns an empty shape. If the shape fill is one of the framed fills and the pen width is greater than zero, the function returns a polygon shape (or a path shape depending on the join shape). If the rectangle has a solid pattern, the function returns a point, line, or polygon as indicated by the pattern. If the rectangle is framed, has a pen width of zero, and has a framed pattern, the function posts the clip_to_frame_shape_unimplemented error. Bitmap patterns are ignored. If one of the grid-constraining attributes is set, this function constrains the geometry to the grid.
polygon	If the shape fill is the noFill shape fill or the shape has no contours, this function returns an empty shape. If the shape fill is one of the framed fills and the pen width is greater than zero, the function returns a polygon shape (or a path shape depending on the caps and join). If the shape has a solid pattern, the function returns a point, line, or polygon as indicated by the pattern. If the polygon is framed, has a pen width of zero, and has a framed pattern, the function posts the clip_to_frame_shape_unimplemented error. Bitmap patterns are ignored. If one of the grid-constraining attributes is set, this function constrains the geometry to the grid.
path	If the shape fill is the noFill shape fill or the shape has no contours, this function returns an empty shape. If the shape fill is one of the framed fills and the pen width is greater than zero, the function returns a path shape. If the shape has a solid pattern, the function returns a point, line, or polygon as indicated by the pattern. If the path is framed, has a pen width of zero, and shape has a framed pattern, the function posts the clip_to_frame_shape_unimplemented error. Bitmap patterns are ignored. If one of the grid-constraining attributes is set, this function constrains the geometry to the grid.

If you provide a target shape that is not one of the geometric shape types, this function performs the actions described in the following table:

Shape type	Action taken
bitmap	Constrains the bitmap position to an integer grid position if one of the grid-constraining attributes is set
picture	Posts the notice shape_already_in_primitive_form
text	Converts to glyph shape; constrains the text position to an integer grid position if one of the grid-constraining attributes is set; converts to an empty shape if appropriate
glyph	Constrains the glyph positions to integer grid positions if one of the grid-constraining attributes is set; eliminates any nil styles and complex styles; converts to an empty shape if appropriate
layout	Converts to a glyph shape; converts to an empty shape if appropriate

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
shape_access_not_allowed
functionality_unimplemented	(debugging version)
clip_to_frame_shape_unimplemented	(debugging version)
Warnings
unable_to_traverse_open_contour_that_starts_or_ends_off_the_curve
	(debugging version)
face_override_style_font_must_match_style
Notices (debugging version)
shape_already_in_primitive_form

SEE ALSO

For examples using this function, see "Converting a Shape to Primitive Form" beginning on page 4-38.

For more information about the primitive form of shapes and for examples of functions that use shapes in their primitive form, see Chapter 3, "Geometric Styles," in this book.

To eliminate unnecessary geometric points, use the GXReduceShape function, described on page 4-74. To simplify a shape's contours, use the GXSimplifyShape function, described on page 4-76.